home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 August / Macworld (1999-08).dmg / Shareware World / Info / For Developers / MADE 1.4.0 / Essentials / Essential Headers.h < prev    next >
Text File  |  1999-05-26  |  8KB  |  199 lines
  1. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  2. /*                                                                   */
  3. /*        MADE - Macintosh Application Development Essentials        */
  4. /*        ---------------------------------------------------        */
  5. /*           (c) Sig Software, http://www.sigsoftware.com/           */
  6. /*                                                                   */
  7. /* These files can only be used for experimental purposes. To obtain */
  8. /* fully commented code, source code for the functions in Essential  */
  9. /*   Extras.h and permission for usage in final projects, you must   */
  10. /*    purchase a license. See documentation for more information.    */
  11. /*                                                                   */
  12. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  13. /*                                                                   */
  14. /*  Essential Headers.h                                              */
  15. /*  -------------------                                              */
  16. /*                                                                   */
  17. /*  Prototypes and globals generally used by MADE and your code.     */
  18. /*                                                                   */
  19. /*  Version 1.0.0 - 10th November 1996                               */
  20. /*  Version 1.2.0 - 20th November 1998 - Browser not found error     */
  21. /*  Version 1.4.0 - 26th May 1999 - Linked lists, better errors      */
  22. /*                                                                   */
  23. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  24.  
  25. #include "User Settings.h" // so you never need to include this manually
  26.  
  27. /*
  28.     Error stuff
  29. */
  30.  
  31. #define        System_Software_Version_Error    1996 // use when needed OS is missing
  32. #define        Browser_Not_Found_Error            1997 // returned by URL code
  33.  
  34. typedef     OSErr Error;
  35.  
  36. void        TestError(Error error);
  37.                 // displays relevant error dialog if error is non-zero
  38. Error        TestResError(void* resource);
  39.                 // checks for zero handle, ResError, shows dialog and returns error code
  40. Error        TestMemError(void* pointer);
  41.                 // checks for zero pointer, MemError, shows dialog and returns error code
  42.  
  43. /*
  44.     About error hiding: for some operations, you will want MADE not to show errors to the user,
  45.     for example when accepting a drag-and-drop. Before beginning these operations, call
  46.     HideErrors() with a pointer to the variable you want to catch errors in instead of showing
  47.     an alert. This lets you call TestError with impunity. HideErrors() can be nested but...
  48.     You MUST call ShowErrors after, and at the same level in your code as HideErrors
  49. */
  50.  
  51. Boolean        HideErrors(Error* keepError);
  52.                 // hide all subsequent errors, catching them in your error variable
  53.                 // return true if successful, otherwise abandon the operation
  54. void        ShowErrors();
  55.                 // removes the most recently added error hiding
  56.  
  57. /*
  58.     About error contexts: when MADE reports an error to the user, it can supply additional
  59.     information about what your application was currently doing. The plain error text is
  60.     "An error occurred." - anything you add in will be inserted before the period, for example
  61.     AddErrorContext("\p while saving a file") -> "An error occurred while saving a file."
  62.     You can also nest error contexts in which case the latter added context is prefixed first.
  63.     For example: AddErrorContext("\p while quitting"); AddErrorContext("\p while saving a file");
  64.     will give you "An error occurred while saving a file while quitting." Clever, eh?
  65.     You MUST call RemoveErrorContext after, and at the same level in your code as AddErrorContext
  66. */
  67.  
  68. Boolean        AddErrorContext(Str255 contextString);
  69.                 // add a new error context string for all subsequent error reports
  70.                 // return true if successful, otherwise abandon the operation
  71. void        RemoveErrorContext();
  72.                 // remove the most recently added error context
  73.  
  74. /*
  75.     Assertion stuff
  76.     
  77.     The point of assertions is to allow you to put checks into your source code which are performed while
  78.     your project is under development, but which are skipped over in the final release for speed's sake.
  79.     This lets you have extensive, slow, laborious double-checks without burdening your eventual users. 
  80. */
  81.  
  82. #if Project_Under_Development
  83.  
  84. void        HandleAssertFailure(char* file, char* date, int line); // params shown in dialog
  85.  
  86. #define        Assert(test)    { if (!(test)) HandleAssertFailure(__FILE__, __DATE__, __LINE__); }
  87.                 // calls failure handler with necessary parameters if text fails
  88.                 // NOTE : If Pool Strings is off under CodeWarrior C/C++ this will cause
  89.                 // unnecessary code expansion because of all the file names and dates.
  90. #else
  91.  
  92. #define        Assert(test)    ;
  93.                 // all Assertions do nothing if project not under development
  94. #endif
  95.  
  96. #define        AssertRange(test, minimum, maximum)    Assert(((test)>=(minimum))&&((test)<=(maximum)));
  97.                 // Asserts test is within minimum and maximum values
  98.  
  99. /*
  100.     Linked list routines
  101.     
  102.     This lets you set up easy linked lists of pointer-allocated memory. 
  103.     To use, the data structures to be linked MUST have the next pointer as the
  104.     first 4 bytes. The pointer to the first must also be initialised to 0. See
  105.     error string storage code for an example.
  106. */
  107.  
  108. void        AddToLinkedList(void** firstPointer, void* addItem, void* beforeItem);
  109.                 // add the structure pointed to by addItem to the list starting at *firstPointer
  110.                 // before item beforeItem - pass zero to put in at the end
  111. void        RemoveFromLinkedList(void** firstPointer, void* removeItem);
  112.                 // removes the item pointed to by removeItem from the list starting at *firstPointer
  113.                 // doesn't actually de-allocate the memory for removeItem
  114. void*        GetLinkedListItem(void* firstPointer, long itemNumber);
  115.                 // get item number itemNumber from list starting at firstPointer, item number starts from 0
  116. long        CountLinkedListItems(void* firstPointer);
  117.                 // counts the number of items in linked list starting at firstPointer
  118.  
  119. /*
  120.     Memory allocation and destruction routines
  121. */
  122.  
  123. void*        AllocPtr(Error* error, Size allocate);
  124.                 // try to create non-movable memory block
  125. void**        AllocHandle(Error* error, Size allocate);
  126.                 // try to create movable memory block
  127. void        DestroyPtr(void* pointer);
  128.                 // destroy non-movable memory block
  129. void        DestroyHandle(void** handle);
  130.                 // destroy movable memory block
  131.  
  132. /*
  133.     Memory locking and unlocking routines. Whenever locking or unlocking handlers,
  134.     use these, not the system calls HLock and HUnlock. If the relevant settings are on,
  135.     these will then check the Handle's status actually changes when you lock/unlock it.
  136. */
  137.  
  138. #if Project_Under_Development && Assert_Memory_Locking
  139.  
  140. void        LockHandleAssert(void** handle);
  141. void        UnlockHandleAssert(void** handle);
  142.  
  143. #define        LockHandle(handle) LockHandleAssert(handle)
  144. #define     UnlockHandle(handle) UnlockHandleAssert(handle)
  145.                 // these versions check the status is changed
  146. #else
  147.  
  148. #define        LockHandle(handle) HLock((Handle)(handle))
  149. #define        UnlockHandle(handle) HUnlock((Handle)(handle))
  150.                 // these versions call the normal Mac Toolbox        
  151. #endif
  152.  
  153. /*
  154.     Useful miniature labels for catching error conditions five levels deep
  155. */
  156.  
  157. #define _e        failed:;
  158. #define    _e2        failed2:;
  159. #define _e3        failed3:;
  160. #define _e4        failed4:;
  161. #define _e5        failed5:;
  162.  
  163. #define _g        goto failed;
  164. #define _g2        goto failed2;
  165. #define _g3        goto failed3;
  166. #define _g4        goto failed4;
  167. #define _g5        goto failed5;
  168.  
  169. #define    _i(p)    { if (p) _g }
  170. #define    _i2(p)    { if (p) _g2 }
  171. #define    _i3(p)    { if (p) _g3 }
  172. #define    _i4(p)    { if (p) _g4 }
  173. #define    _i5(p)    { if (p) _g5 }
  174.  
  175. /*
  176.     Crucial global variables
  177. */
  178.  
  179. extern Boolean        applicationHasQuit;        // set high to end event loop
  180. extern void*        dummy;                    // used for discarding unwanted results
  181. extern WindowPtr    frontWindow;            // which Window is in front of the rest
  182. extern Boolean        appInFront;                // whether the application is currently in front
  183. #if Use_Drag_Manager
  184. extern Boolean        hasDragManager;            // if the drag manager is installed
  185. #endif
  186.  
  187. /*
  188.     Useful functions
  189. */
  190.  
  191. Boolean            CheckGestaltBit(OSType selector, char bit); // for determining environment
  192. void            ShowResCursor(short cursorID); // loads cursor from resource and displays
  193. #if Use_Drag_Manager
  194. void            CreateDragRegion(RgnHandle region);
  195.                     // Turns the given region in local co-ordinates into a drag frame region in
  196.                     // global co-ordinates, using the current active GrafPort. This is very
  197.                     // useful for initialising drags with TrackDrag().
  198. #endif
  199.